Adding descriptor generator #180

AmosOO7 · 2025-05-02T01:51:13Z

Pull Request: Add `descriptor` Subcommand (Generate & Info)

Description

This PR introduces a new descriptor subcommand to the BDK CLI that enables users to generate and inspect Bitcoin wallet descriptors for internal and external paths, supporting common BIP standards (44, 49, 84, 86). It includes support for both single-path and multipath descriptors from extended keys (xprv/xpub or tprv/tpub).

This resolves issue #175

Note: The --weak option for string-based key generation is intentionally excluded in this PR, pending further instruction.

Features Implemented

Adds new descriptor subcommand with:
- generate – generate new descriptors
- info – inspect and display descriptor metadata
Supports BIP44, BIP49, BIP84, and BIP86 script types
Generates internal and external descriptors
Supports --multipath for wildcard derivation paths
Rejects mismatched key-network pairs (e.g., xprv on testnet)
Reasonable defaults:
- --type defaults to 84 and a short t
- --network default testnet
- --multipath defaults to false and a short m

Usage Examples

1. Generate Descriptors from an Extended Private Key

cargo run -- --network testnet descriptor generate --type 84 <XPRV>

2. Generate Descriptors from a Mnemonic (no key provided)

cargo run -- --network testnet descriptor generate --type 86

3. Generate Multipath Descriptors from an Extended Public Key or Private Key

cargo run -- --network testnet descriptor generate --type 44 --multipath <XPUB/XPRIV>

4. Show Info about an Existing Descriptor

cargo run -- --network testnet descriptor info "wpkh([fingerprint/84h/1h/0h]xpub/0/*)"

I've signed all my commits
I followed the contribution guidelines
I ran cargo fmt and cargo clippy before committing

New Features:

I've added tests for the new feature
I've added docs for the new feature
I've updated CHANGELOG.md

src/commands.rs

Cargo.toml

src/commands.rs

src/descriptor_handler.rs

tvpeter

Good work Amos.

Most of the fns in utils should be in the handlers file, while most of those in handlers should be placed in the utils.

Cargo.lock

src/handlers.rs

tvpeter

Thank you for your work on this, @AmosOO7.

If possible, please revert the imports you removed, as this will help in tracking your imports. Also, kindly remove any unnecessary comments and squash your commits into logical groupings. I have also left comments on other specific areas for your review.

Thank you!

src/handlers.rs

src/commands.rs

src/handlers.rs

src/utils.rs

tvpeter

Thank you for continuing to work on this.

I have left a couple of comments.

src/handlers.rs

src/utils.rs

src/commands.rs

src/handlers.rs

coveralls · 2025-06-24T20:00:27Z

Pull Request Test Coverage Report for Build 18042035740

Details

0 of 294 (0.0%) changed or added relevant lines in 2 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-1.7%) to 6.949%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/handlers.rs	0	34	0.0%
src/utils.rs	0	260	0.0%

Totals
Change from base Build 17621040142:	-1.7%
Covered Lines:	105
Relevant Lines:	1511

💛 - Coveralls

tvpeter

Thanks @AmosOO7 for continuing to work on this.

The checks for path and how a user can use it is a little bit confusing. I think we might need to split it into subcommands, similar to how key has generate, derive and restore. If you have any suggestions for the best subcategories, please feel free to share them in the conversation before continuing with the implementation. Otherwise, I will propose the subcategories this coming week to make it clearer. I've also left some additional comments for you.

Additionally, it would be a good idea to include documentation comments for each command option and parameter to help users better understand their functionalities.

Thank you.

src/commands.rs

src/handlers.rs

AmosOO7 · 2025-07-16T22:45:45Z

After having a discussion with @tvpeter and following his suggestions.

Breaking the descriptor command into subcommands improves clarity, usability, and future extensibility of the BDK CLI.

Suggested Subcommands for `descriptor`

Subcommand	Description
from-key	Generate descriptors from a provided Xprv or Xpub
from-mnemonic	Generate descriptors from a newly generated or provided BIP39 mnemonic
multipath	Generate multipath (wildcard derivation) descriptors from a key
info (optional/future)	Inspect a descriptor and show parsed structure (e.g., key origin, type, script)

Detailed Breakdown

1. `descriptor from-key`

Input: --type, <XPRV | XPUB>
Optional: --path m/84h/1h/0h (for custom derivation base)
Output: external/internal descriptor strings
Optionally support both single and multipath modes via --multipath

2. `descriptor from-mnemonic`

Input: --type,
Optional: --mnemonic <WORDS> (if not, generate randomly)
Output: same as from-key, plus return mnemonic used

3. `descriptor multipath`

Input: --type, <XPRV | XPUB>
Output: wildcard descriptors (e.g., /0/* and /1/*)

4. (Optional) `descriptor info`

Input: descriptor string
Output: parsed structure, origin, derivation, checksum, script type, etc.

Example CLI Usage


From key
bdk-cli descriptor from-key --type 84 <XPRV | <XPUB>;
From mnemonic
bdk-cli descriptor from-mnemonic --type 86 (optional)<WORDS>
From key with multipath
bdk-cli descriptor multipath --type 44 <XPUB | <XPUB>;
Descriptor info (optional)
bdk-cli descriptor info "wpkh([abcd1234/84'/1'/0']xpub.../0/*)"

What do you think about the suggestions @tvpeter and @notmandatory ?

tvpeter · 2025-07-17T04:26:24Z

I think the following is more descriptive:

From key

bdk-cli descriptor from-key --type 84 <XPRV | ;

bdk-cli --network [network] descriptor generate --type [type] --key <xprv | xpub>

From mnemonic

bdk-cli descriptor from-mnemonic --type 86 (optional)

bdk-cli --network [network] descriptor generate --type [type] --mnemonic [mnemonic]

From key with multipath

bdk-cli descriptor multipath --type 44 <XPUB | ;

bdk-cli --network [network] descriptor generate --type [type] --multipath <xprv|xpub>

Descriptor info (optional)

bdk-cli descriptor info "wpkh([abcd1234/84'/1'/0']xpub.../0/*)"

bdk-cli --network [network] descriptor --info <descriptor>

note:

<param> - required
[param] - optional as defaults are provided

Also, wait for confirmation from Notmandatory.

notmandatory · 2025-07-17T14:10:23Z

@tvpeter I agree that having two descriptor sub-commands generate and info makes sense. Also good for generate sub-command to have optional --type with default being 84. One other suggestion is that I think you can remove the --key and --mnemonic options and just require a key in either xprv OR mnemonic format, we should be able to parse either format into a key. But if that turns out to be too hard it's OK to be explicit and use --key and --mnemonic mutually exclusive but required options.

Having the descriptor info <descriptor> is nice to have but not sure it's that useful since you can see this info by just looking at the descriptor. But could still be useful as a training tool to show people what each part is for new people.

tvpeter · 2025-07-17T14:45:33Z

One other suggestion is that I think you can remove the --key and --mnemonic options and just require a key in either xprv OR mnemonic format, we should be able to parse either format into a key. But if that turns out to be too hard it's OK to be explicit and use --key and --mnemonic mutually exclusive but required options.

Having the descriptor info <descriptor> is nice to have but not sure it's that useful since you can see this info by just looking at the descriptor. But could still be useful as a training tool to show people what each part is for new people.

@AmosOO7, you should be able to update according to this. Thank you

tvpeter

Hi @AmosOO7,

Thanks for continuing to push this PR. I have left comments, when you address them, I will continue with testing.
Thank you

src/handlers.rs

src/error.rs

src/commands.rs

src/handlers.rs

src/error.rs

tvpeter · 2025-09-04T11:14:08Z

@AmosOO7, can you please make time to update this PR? I was hoping it could make it into the next release. It would be great if you could push it forward.
Thank you.

tvpeter

Thank you for your efforts on this PR @AmosOO7

I have left comments but don't worry, I will push changes so that it is easier for us to close the PR.
Thank you.

src/utils.rs

src/handlers.rs

src/utils.rs

- Created Subcommnds for the descriptor command; generate - Created function to get descriptors from mnemonics

- add generating multipath descriptors - add pretty formatting for descriptors

notmandatory · 2025-09-27T01:16:15Z

Unfortunately this PR needs a lot of cleanup, I've briefly discussed with @tvpeter and he'll help rework it when he has time. Problems I initially ran into:

shouldn't use bip #s which don't represent descriptor types, they are derivation paths which are related but different, descriptor types are: https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md#features. Descriptor types we should focus on are P2PKH, P2WPKH, and P2TR (key spend).
shouldn't use value_parser = PossibleValuesParser should do similar to Compile.script_type or create an enum of descriptor types we support
when I tested the multipath flag it only works for public keys, but should work if an auto generated privkey, manual priv key, or manual public key is given, or could leave this out of this PR and do in a follow-up PR.
minor but still confusing, the command is bdk-cli descriptor generate <flags> <key> but no other sub-commands only generate. should be like the top level "compile" command

tvpeter reviewed May 6, 2025

View reviewed changes

src/commands.rs Outdated Show resolved Hide resolved

AmosOO7 marked this pull request as ready for review May 7, 2025 14:17

AmosOO7 force-pushed the adding_descriptor_generator branch from 09b4f4a to ebf6be3 Compare May 7, 2025 16:23

tvpeter requested changes May 12, 2025

View reviewed changes

AmosOO7 requested a review from tvpeter May 19, 2025 16:21

tvpeter requested changes May 21, 2025

View reviewed changes

Cargo.lock Outdated Show resolved Hide resolved

src/handlers.rs Outdated Show resolved Hide resolved

AmosOO7 requested a review from tvpeter May 22, 2025 12:31

notmandatory added this to BDK-CLI May 28, 2025

notmandatory moved this to In Progress in BDK-CLI May 28, 2025

notmandatory added the enhancement New feature or request label May 28, 2025

notmandatory assigned AmosOO7 May 28, 2025

notmandatory added this to the CLI 1.1.0 milestone May 28, 2025

tvpeter requested changes Jun 4, 2025

View reviewed changes

AmosOO7 force-pushed the adding_descriptor_generator branch 7 times, most recently from 6bff257 to 31f256a Compare June 12, 2025 11:45

tvpeter requested changes Jun 12, 2025

View reviewed changes

AmosOO7 force-pushed the adding_descriptor_generator branch from 15495c4 to 6c8e714 Compare June 21, 2025 16:55

AmosOO7 requested a review from tvpeter June 22, 2025 08:33

tvpeter requested changes Jul 5, 2025

View reviewed changes

src/commands.rs Outdated Show resolved Hide resolved

src/commands.rs Outdated Show resolved Hide resolved

src/handlers.rs Outdated Show resolved Hide resolved

src/handlers.rs Outdated Show resolved Hide resolved

AmosOO7 requested a review from tvpeter July 27, 2025 18:44

tvpeter requested changes Aug 19, 2025

View reviewed changes

AmosOO7 requested a review from tvpeter September 5, 2025 10:49

tvpeter requested changes Sep 23, 2025

View reviewed changes

tvpeter force-pushed the adding_descriptor_generator branch from 37ce428 to 3ba1dc0 Compare September 24, 2025 17:44

AmosOO7 and others added 2 commits September 26, 2025 15:22

feat: add descriptor generation

193b9cd

- Created Subcommnds for the descriptor command; generate - Created function to get descriptors from mnemonics

fix descriptors generation

618bf39

tvpeter force-pushed the adding_descriptor_generator branch from 3ba1dc0 to 483a7f8 Compare September 26, 2025 14:27

feat(descriptors): add multipath descs and pretty

1452eaa

- add generating multipath descriptors - add pretty formatting for descriptors

tvpeter force-pushed the adding_descriptor_generator branch from 483a7f8 to 1452eaa Compare September 26, 2025 15:23

tvpeter requested a review from notmandatory September 26, 2025 15:28

Adding descriptor generator #180

Are you sure you want to change the base?

Adding descriptor generator #180

Uh oh!

Conversation

AmosOO7 commented May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request: Add descriptor Subcommand (Generate & Info)

Description

Features Implemented

Usage Examples

1. Generate Descriptors from an Extended Private Key

2. Generate Descriptors from a Mnemonic (no key provided)

3. Generate Multipath Descriptors from an Extended Public Key or Private Key

4. Show Info about an Existing Descriptor

New Features:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tvpeter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tvpeter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tvpeter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coveralls commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 18042035740

Details

💛 - Coveralls

Uh oh!

tvpeter left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AmosOO7 commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Suggested Subcommands for descriptor

Detailed Breakdown

1. descriptor from-key

2. descriptor from-mnemonic

3. descriptor multipath

4. (Optional) descriptor info

Example CLI Usage

From key

From mnemonic

From key with multipath

Descriptor info (optional)

Uh oh!

tvpeter commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

From key

From mnemonic

AmosOO7 commented May 2, 2025 •

edited

Loading

Pull Request: Add `descriptor` Subcommand (Generate & Info)

coveralls commented Jun 24, 2025 •

edited

Loading

tvpeter left a comment •

edited

Loading

AmosOO7 commented Jul 16, 2025 •

edited

Loading

Suggested Subcommands for `descriptor`

1. `descriptor from-key`

2. `descriptor from-mnemonic`

3. `descriptor multipath`

4. (Optional) `descriptor info`

tvpeter commented Jul 17, 2025 •

edited

Loading

notmandatory commented Jul 17, 2025 •

edited

Loading

notmandatory commented Sep 27, 2025 •

edited

Loading